<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Local Storage Tutorial - Gears API - Google Code</title>
<link href="codesite.css" type="text/css" rel="stylesheet"/>
</head>
<body class="gc-documentation">

<div id="gc-container">

<div id="codesiteContent">

<a name="gc-topnav-anchor"></a>
<div id="gc-topnav">
<h1>Gears Codelab</h1>
<ul id="docs" class="gc-topnav-tabs">
<li>
<strong>Taiwan Google Developer Day 2008&nbsp;</strong>
</li>
</ul>
</div> <!-- end gc-topnav -->


<div style="position: relative;" class="g-unit" id="gc-pagecontent">


<h1 class="page_title">Local Storage</h1>

<p>Any static HTML files, such as documentation, can be enabled for viewing
offline by following these steps. This tutorial shows you how to create a
manifest file, and make your files available offline, using Gears. (Time
estimate: 30 minutes.)</p>

<h4>You will need:</h4>
<ul>
<li>Ability to edit basic JavaScript</li>
<li>Ability to publish files to an HTTP server that hosts your files</li>
<li>The static files that you want to enable for offline viewing</li>
<li>Firefox 2</li>
</ul>

<h1>Setting Up Your Environment</h1>

<h3>[ ] Make sure you have Firefox 2 installed</h3>

<p>To make debugging and answering questions easier during the lab, we will use
a common browser. Download the browser from <a href="http://www.moztw.org">Mozilla Taiwan</a> [1],
if you don't already have a copy.</p>

<h3>[ ] You need a web server</h3>

<p>Gears uses the domain part of the URL to segregate the offline cache and to
manage cross domain interaction. Ideally, you should use your own web server
whether locally or on a hosted service. If you do not have either of these, ask
one of the teaching assistants to provide you an account on our local web
server.</p>

<h3>[ ] Get Gears and related tools</h3>

<ol>
  <li>Go to <a href="http://gears.google.com">gears.google.com</a> in Firefox 2 and download the plugin.</li>
  <li>Download the <code>gears_init.js</code> file from Gears' <a href="http://code.google.com/apis/gears/tools.html">Resources and Tools</a> [2] page.</li>
</ol>

<p>[1] http://www.moztw.org<br/>
   [2] http://code.google.com/apis/gears/tools.html</p>

<h1>Basic Content Setup</h1>


<h3>[ ] Create a very basic webpage</h3>

<p>You can either grab some content you have already or create a new "Hello
World" page with some text. This will be the page that we will be taking
offline in this codelab.</p>

<p>Add the following script into the webpage to initialize gears:</p>

<pre><code>&lt;script type="text/javascript" src="gears_init.js"&gt;&lt;/script&gt;
</code></pre>

<h3>[ ] Create your first Gears javascript file</h3>

<p>Take the following text and create a <code>hello.js</code> file. You can
either fill in your own implementation of <code>textOut()</code> or just use
<code>alert()</code>. <em>NB: When loading the page, it should ask you for permission
to allow it to use Gears. Choose "Accept" to continue the lab.</em></p>

<pre><code>var localServer;

// Called onload to initialize local server
function init() {
  if (!window.google || !google.gears) {
    alert("NOTE: You must install Gears first.");
  } else {
    localServer = google.gears.factory.create("beta.localserver");
    alert("Yay, Gears is already installed.");
  }
}</code></pre>


<h2>Assignment #1</h2>

<p>Show that your web page can display the text, "<strong>Yay, Gears is already
installed.</strong>", from the web page you created above</p>

<h2>Manifest File</h2>

<h3>[ ] Create a manifest file</h3>

<p>In your content directory, create a manifest file called
<code>manifest.json</code> with content simlar to the following. Modify the
<code>entries</code> list to match files you are trying to make offline. The
version string is updated anytime the resources on your website change.</p>

<pre><code>{
  "betaManifestVersion": 1,
  "version": "1.0.0",
  "entries": [
    {"url": "hello.html"},
    {"url": "hello.js"},
    {"url": "gears_init.js"}
  ]
}</code></pre>

<p class="note"><strong>Note:</strong> The URLs can be fully-qualified, for example <a
href="">http://www.example.com/index.html</a>, or they can be relative to the
manifest file's location.</p>

<h2>Using the LocalServer ManagedStore</h2>

<h3>[ ] Add function to create the store</h3>

<pre><code>var STORE_NAME = "hello_world";
var MANIFEST_FILE = "manifest.json";
var store;

// Create the managed resource store
function createStore() {
  store = localServer.createManagedStore(STORE_NAME);
  store.manifestUrl = MANIFEST_FILE;
  store.checkForUpdate();

  var timerId = window.setInterval(function () {
    if (store.currentVersion) {
      window.clearInterval(timerId);
      alert("The documents are now available offline. The version is: " +
            store.currentVersion);
    } else if (store.updateStatus == 3) {
      alert("Error: " + store.lastErrorMessage);
    }
  }, 500);
}</code></pre>


<h3>[ ] Add function to remove the store</h3>

<pre><code>// Remove the managed resource store.
function removeStore() {
  localServer.removeManagedStore(STORE_NAME);
  alert("Done. The local store has been removed." +
        "You will now see online versions of the documents.");
}</code></pre>

<h3>[ ] Add buttons to your webpage</h3>

<p>Be sure to add some buttons to your web page that invokes the functions you just added.</p>

<h2>Assignment #2</h2>

<p>Show that your web page can be viewed while working offline.</p>

<p class="note"><strong>Note:</strong> Flush your browser cache. Better yet, make your cache
size <code>0 MB</code> during this codelab.</p>

<p class="note"><strong>Note:</strong> When updating any of your files, remember to update
the version in the manifest file. Otherwise, the local cache will not be
updated with the latest version.</p>

</div><!-- end gc-pagecontent -->
</div> <!-- end codesite content -->

<hr/>
<div id="gc-footer" dir="ltr"> 
<div id="gc-footer-img"></div>
<div class="text">
Copyright 2008 Google Inc.
</div>
</div><!-- end gc-footer -->

</div><!-- end gc-container -->
</body>
</html>
